<!DOCTYPE html> 
<!--
 Copyright (c) 2016 - 2019 fortiss GmbH, Herwig Eichler
               2019 Johannes Kepler University Linz
  
 This program and the accompanying materials are made available under the
 terms of the Eclipse Public License 2.0 which is available at
 http://www.eclipse.org/legal/epl-2.0.

 SPDX-License-Identifier: EPL-2.0
 
 Contributors:
   Jose Cabral, Herwig Eichler, Alois Zoitl
     - initial API and implementation and/or initial documentation
   Bianca Wiesmayr
	 - text corrections and updates, add short info for contributions
-->

<html lang="en">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<title>Contributing to FORTE</title>
	<link rel="stylesheet" type="text/css" href="../help.css">
</head>

<body>

	<h1 id="topOfPage">Contributing to FORTE</h1>
	
		<p>The FORTE project is stored as a Git repository in the Eclipse platform. 
		It's open source, so you can download the project and you can even change things and improve it. 
		But of course, it's not that simple, otherwise changes would be added without any control and could mess up the code.
		If you wish to report a bug, see the section <a href="#BugReport">Bug report</a>.</p>
		
	<h2>Git repository</h2>

		<p>If you don't know what Git is, don't worry, we have all been there. 
		Basically, Git is a distributed system that is used to control various versions of anything, but mostly of software code. 
		The code is stored in a so-called repository which contains all files related to the software. 
		After changing the code, instead of saving new files (fileV1, fileV2, fileFinalVersion, fileThisIsReallyTheFinalVersion, fileThisIsReallyTheFinalVersion2) in a new folder, you just "commit" the change and the changes are saved in the repository. 
		To see older versions of the software, you go to the specific commit. 
		The good thing about Git is the word "distributed" in its definition (I bet you didn't notice it). 
		There's not only one repository, but anyone who wishes to contribute to the repository, copies the whole content of the repository to his/her computer and works there, changes there and commits there. 
		Then, the user pushes to the repository where he/she copied from.</p>
		
		<p>This is only the basic principle of Git, but it should give an idea of how it works. 
		The step-by-step tutorial following below helps to set up Git for your first contributions.
		Plenty of information online helps to learn more about Git.
		Instead of starting from zero, I would recommend having a look at <a target="_blank" href="https://git-scm.com/"> https://git-scm.com/</a> where you can download everything necessary to start contributing to any Git project. 
		The documentation <a target="_blank" href="https://progit2.s3.amazonaws.com/en/2016-03-22-f3531/progit-en.1084.pdf">book</a> about Git provides a good overview. 
		Although the book is very long, you'll only need Chapters 1 and 2 to understand how Git works, and Chapter 3 to understand branches.</p>
		
		<p>But I should warn you, young padawan, learning Git is hard. 
		It's a very powerful tool, but it takes time to understand it. 
		Simply, read the basics and follow the step-to-step guide.
		It is not necessary to try to understand everything before jumping to contributions. 
		The best teacher is practice, so use FORTE as your example for practicing. 
		You can't break anything. 
		Git is bullet-proof.</p>
		
	<h2>Gerrit</h2>
	
		<p>You know how Git works, and have maybe already used it. But now, a new player is in the game: Gerrit. 
		What is it? 
		The information in <a target="_blank" href="https://en.wikipedia.org/wiki/Gerrit_%28software%29">Wikipedia</a> helps, but putting it simple, it is the firewall of contributions. 
		It's used by many platforms, including the Eclipse Foundation where the FORTE repository is. 
		When someone, a programmer with the best intentions, wants to contribute to FORTE code, he clones the Git repository, makes changes, commits and then pushes to the repository in the Eclipse Foundation. 
		But of course, the change doesn't go directly to the repository. 
		First, it has to be accepted by people in charge of FORTE. 
		Therefore, the contributors push to Gerrit. 
		Gerrit checks legal requirements, and then notifies the people responsible of FORTE that some new change has arrived. 
		They then visit Gerrit, see the new change and can accept or deny it. Easy, right?</p>
		
		<p>But to better understand Gerrit, it's better to work with it. We'll go step-by-step toward pushing code to Gerrit in order to contribute to FORTE.</p>
		
	<h2>Help FORTE - NOW!</h2>		
		<p>As said before, we'll learn to contribute to FORTE step-by-step. 
		However, if you want to contribute, you'll need to sign some <a href="#ECA">legal documents</a> online. 
		If you don't wish to sign them, you can still get the code of FORTE and play with it.</p>
		
	<h3 id="EclipseAccount">Create an Eclipse account</h3>
		<p>First of all, you should create an Eclipse account. 
				
		All commits that are created by Eclipse accounts without signed ECA will be rejected automatically. 
		If you don't want to contribute, but just want to download the code and play around, skip to the next step.</p>
								
		<p>To create the Eclipse account, simply go to <a target="_blank" href="https://www.eclipse.org/">https://www.eclipse.org/</a> and click "Create Account" on the top-right of the page. 
		Then, just fill in the information to create an account. 
		The email address indicated during account registration should also be used later in Git.</p>
	
	<h3 id="BugReport">Submit bug reports</h3>
		<p>If you notice an issue related to Eclipse 4diac, you should report a bug via the following link: <a target="_blank" href="https://bugs.eclipse.org/bugs/enter_bug.cgi?product=4DIAC">Bugzilla</a><br>
		You can report issues and suggestions for 4diac IDE, 4diac FORTE, the webpage,... after logging into your (new) Eclipse account.
		Follow the <a target="_blank" href="https://bugs.eclipse.org/bugs/page.cgi?id=bug-writing.html">bug writing guidelines</a> in order to allow other users to understand your issue.
		First, select the component that needs to be improved. 
		Then, enter details about your system: the program version in use as well as your system. 
		If the bug is not related to a certain operating system, choose All.
		The Summary will be the title of the bug and should be concise and descriptive.
		Further details are then added in the description field. 
		Provide all information required to understand and possibly also reproduce a bug.
		Don't hesitate to also report minor issues.</p>
		
	<h3 id="ECA">Sign the ECA</h3>	
		<p>The next step is to sign the ECA (Eclipse Contributor Agreement). 
		This is mandatory in order to contribute to FORTE. 
		Go to the ECA <a target="_blank" href="https://eclipse.org/legal/ECA.php"> page</a> to read it and learn more about it. 
		The ECA protects for example copyrights. 
		Basically, when you sign it, you declare that you have full rights of every contributed change, which helps protecting intellectual property, including your own. 
		If your contribution is part of your work at some company, you should talk first with your superior and the legal department to fully understand how to approach this. </p>
									
		<p>The signing is done online after logging in to your account and selecting the "Eclipse Contributor Agreement".
		You need to check boxes and complete a textbox with "I AGREE". 
		There's no tangible outcome. 
		Eclipse stores your information together with the version of the ECA that you signed. 
		You can print the ECA, but you won't get a certificate to print that says that you signed it. 
		Your account will show that you have signed the ECA and there's a tool in Eclipse validating whether an account has signed it.</p>

     <h3 id="EGit">Use EGit to contribute: Preparations</h3>
		<p>The first example uses Eclipse and all the Git work will be done using EGit, normally installed automatically together with the Eclipse IDE. 
		If you think GUI is for weaks and a real programmer should use command line, you can follow the instructions given <a href="#CommandLine">below</a>. 
		Nevertheless, users without command line experience should stick to Eclipse.</p>

	    <ol>
					<li><p>Get all required software</p>
					
						<p>The first thing to do is to get all the software. 
						Download Eclipse for C++ and install it. 
						If you already have an Eclipse IDE but it's not configured for C++, you don't need to download another Eclipse, but only the C++ plugin. 
						See a tutorial <a target="_blank" href="http://help.eclipse.org/mars/index.jsp?topic=%2Forg.eclipse.cdt.doc.user%2Fgetting_started%2Fcdt_w_install_cdt.htm">here</a>. 
						EGit should be installed automatically with your Eclipse, otherwise follow the steps <a target="_blank" href="http://www.vogella.com/tutorials/EclipseGit/article.html#eclipseinstallationgit">here</a> to install it.</p>
					</li>
					
					<li>
						<p>Configure EGit</p>
					
						<p>The first thing to do in EGit is to configure the user settings.
						The main items are the name and email address. 
						This information is attached to your commits. 
						To do that, just follow the simple steps in section 4.2 of the same <a target="_blank" href="http://www.vogella.com/tutorials/EclipseGit/article.html#eclipseinstallationgit">link</a> as above. 
						In particular, open Window &rarr; Preferences &rarr; Team &rarr; Git &rarr; Configuration in Eclipse.
						Click "Add Entry..." to open a dialog box for a key-value pair.
						As a key enter <code>email</code> and as value enter the email address of your Eclipse account. 
						Click "Add" and add another entry. The second entry consists of the key <code>name</code> and your full name as value.
						As you created the Eclipse account and signed the ECA in the previous <a href="#ECA">step</a>, you must use the same email address.</p>
					</li>
					<li>
						<p>Download FORTE repository</p>
						
						<p>In Eclipse, go to File &rarr; Import...&rarr; Git &rarr; Projects from Git. 
						Click Next and then select Clone URI. 
						Next. 
						Paste https://git.eclipse.org/r/4diac/org.eclipse.4diac.forte in the URI field and then Next. 
						Eclipse will connect to the repository and retrieve all its branches. 
						Select all and click Next. 
						The branches represent various development stages.
						For small updates/fixes to the current version, you can use the branch with the latest version number.
						Select the destination folder of the repository in your local machine and click Next. 
						Wait while the repository is being downloaded. 
						Click Next until the assistant is finished.</p>
					</li>

					<li>
						<p id="ConfigureGerrit">Configure Gerrit</p>
						
						<p>Access the <a target="_blank" href="https://git.eclipse.org/r"> Gerrit </a> page in Eclipse to manage your account details regarding Gerrit.
						Click Sign In in the upper-right corner.
						The username is the email address registered with your Eclipse account created in <a href="#EclipseAccount">step 1.1</a>. 
						Log in with the password of your Eclipse account.
						Then, click on your name on the upper-right corner and choose Settings. 
						There you can change your preferences concerning messages, follow projects, manage your password, ... 
						You can push changes to Gerrit via SSH or https.
						In this example, we'll use https. 
						SSH requires you to create public and private keys, which are stored in files. 
						Eclipse use these files to connect to Gerrit. 
						To know more about creating keys and configuring Eclipse, visit <a target="_blank" href="http://www.vogella.com/tutorials/EclipseGit/article.html#github"> here</a>, and then add the key in the SSH Public Keys setting in Gerrit. 
						</p>
						
						<p>Go to HTTP Password in the Settings page of Gerrit, copy the username that appears and click Generate Password. 
						You'll get a random long password that you'll use every time you want to push something to Gerrit. 
						Go to Eclipse, right-click on the project &rarr; Team &rarr; Show in Repositories View. 
						Then, expand Remotes, and right-click on origin &rarr; Gerrit Configuration.... 
						In this step, you can choose ssh, https or another communication protocol. 
						Choose https and paste your username from Gerrit to the field User. 
						This will change the Push URI. 
						In the Destination branch field, you should set the branch to push to.
						You can't push to a branch that doesn't exist in the Gerrit repository. 
						Note that the destination branch begins with refs/for/. 
						Click finish and see in the Repositories View that the Origin remote has changed the push URI. 
						This means that when you send something to FORTE, it will send to Gerrit, but when you get something from it, you'll get it from the actual repository. </p>
					</li>
					
					<li>
						<p id="Branches">(Optional) Look around and move between branches</p>
						
						<p>Now you have the newest FORTE code. 
						After downloading the code of a project, look around first. 
						Check the folders, read the documentation and readme files. 
						Try to understand the folders and hierarchies. </p>
						
						<p>Right-click on a project in the Eclipse package explorer and select Team.
						There you find all possible commands for EGit. 
						Team &rarr; Show in History will show you all the commits in the current branch. 
						Normally, master is the main branch. 
						If FORTE has another branch, and you want to work with it, you'll have to create a local branch that serves as reference of the original branch. 
						That is, the Eclipse repository has a master branch (seen as origin/master), and for example a develop branch (seen as origin/develop). 
						But you, locally, have only a master branch (seen as master). 
						This local master is a reference to the origin/master and everything you change on it, will be then pushed to the origin/master. 
						But if you want to work on the origin/develop branch, you'll need to create a local branch that references it. 
						Details on branches can be found in the <a target="_blank" href="https://progit2.s3.amazonaws.com/en/2016-03-22-f3531/progit-en.1084.pdf">book</a> mentioned above (chapter 3).</p>
						
						<p>Right-click on the project &rarr; Team &rarr; Switch To &rarr; Other.... 
						There you'll see the local and remote branches. 
						Select the remote branch you want to work on, for example origin/develop, and click Checkout. 
						You'll get a message saying that you can watch the remote branch, or you can create a new branch locally to work on it. 
						Click on "Checkout as New Local Branch" and then select a name for the local branch. 
						Usually, the name of the original branch is copied, therefore, we'll call it develop (without the part "origin/") and click finish. 
						Now you can switch between the branches, and the changes in each one will be reflected in the corresponding origin. </p>
						
						<p>The FORTE projects follows the workflow shown <a target="_blank" href="http://nvie.com/posts/a-successful-git-branching-model/">here</a>. 
						Basically, the master branch is used to release versions and the development of new stuff. 
						You should always branch out from develop to work on something new.</p>
					
					</li>
				</ol>
				
<h3>Create contributions with Eclipse and EGit</h3>
	<p>After you downloaded the current code, you can start creating contributions.
				<ol>
					<li> 
						<p id="FindBug">Find a bug to work on</p>
						
						<p>In order to contribute, you need to first find a bug to work on. 
						All your changes should be related to a bug recorded in <a href="#BugReport">Bugzilla</a>. 
						You can look into the code and find something wrong or you can go to the <a target="_blank" href="https://bugs.eclipse.org/bugs/buglist.cgi?list_id=14410991&product=4DIAC&query_format=advanced"> list of bugs</a> and see the ones that refer to the FORTE project. 
						If you find an error, or even missing documentation, you should report the bug. 
						In order to learn how to contribute you may want to edit some documentation.
						Maybe you find a typo or you'd like to add some details.
						Bug fixes are a metric that shows how the software development progresses. 
						But be aware that when reporting a bug, it should have a clear way of fixing it. 
						For a reported bug such as "Missing documentation", it is unclear when the bugfix is complete. 
						Therefore, state for example which documentation is missing.
						Each bug in Bugzilla has an ID.
						Let's say we are working on bug number 123456.</p>
					</li>
					<li>
						<p>Make changes and prepare to commit</p>
						
						<p>Now you actually change the code. 
						Open the files you want to change and edit them. 
						Try to change less then 1000 lines in one commit in order to keep individual commits small.
						Larger edits can be split to several commits.</p>
						
						<p>Open the Git Staging View in Eclipse by going to Window &rarr; Show View &rarr; Other... &rarr; Git &rarr; Git Staging. 
						In the Unstaged Changes you see all the files that were changed. 
						Right-click on them and then Add to index. 
						The selected files will be moved to Staged Changes.</p>
					</li>
					<li>
						<p id="CommitChanges">Commit the changes</p>
						
						<p>Committing changes is a very important step. 
						The changes are first committed locally.
						The commit message is essential for pushing to Gerrit, you can find example messages below.
						In Gerrit, the commit is first verified to ensure that everything is fine and the changes are then accepted.
						The commit message is created in the Git Staging View and consists of three parts: the subject, the body and the footer. 
						The three parts are separated by an empty line.</p>
						
						<ul>
							<li>
								<p>The subject must contain the number of the bug you are working on, listed between square brackets and followed by a short explanation of what the commit contains.
								Try to keep it shorter than 50 characters and, for better readability, start the message with a capital letter. 
								Don't use a period at the end of the subject.</p>
							</li>
							<li>
								<p>The body contains all the explanation of what was done. Use it to explain what and why, but not how.</p>
							</li>
							<li>
								<p>The footer must have two parts (three if the Change-Id is needed): </p>
									<ol>
										<li>[ALWAYS] the link to the bug (Bug: https://bugs.eclipse.org/bugs/show_bug.cgi?id=123456 )</li>
										<li>[ONLY TO OVERWRITE A COMMIT] the Change-Id field is used when you are adding the second commit to a change already pushed before (for example: Change-Id: If0b359ad15268ed179194cf5ad4fb5b2d09b3290). See NOTE 2 to know more about when to use it.</li>
										<li>[ALWAYS] the signing field (Signed-off-by: John Doe &lt;johndoe@gmail&gt;). 
										Sign via the button showing a brush that is located above the Commit Message.
										The signature at the end is checked by Gerrit to verify that the committer has signed the ECA.</li>
									</ol>

									<p>NOTE: Empty lines are only allowed (and mandatory) between the subject, body and footer, not between the inner parts of the footer.</p>
									<p>NOTE 2: The Change-Id is not edited, when a commit is pushed to Gerrit for the first time (CommitOne).
									Gerrit generates the Change-Id. 
									If CommitOne is rejected (erroneous code, missing information, etc.), you must revise the commit and amend (overwrite) the CommitOne.
									This generates CommitTwo.
									(You could also delete CommitOne completely, and create a new commit as CommitTwo). 
									Remember that CommitTwo is a completely new commit. 
									CommitTwo must have the Change-Id that Gerrit generated for CommitOne (Go to the Gerrit webpage, find the change of CommitOne and you'll see its Change-Id). 
									When you push CommitTwo, it won't create a new entry in Gerrit.
									Instead, CommitTwo will appear below CommitOne on the same page. 
									Now CommitTwo is waiting to be accepted.</p>
							</li>
						</ul>
						
						<p>Example for CommitOne:</p>
						
						<ul>
							<li>
								<p>[123456] Change the initial value of temp variable</p>

								<p>The initial value of the temp variable was changed to 1 instead of zero because of weather conditions</p>

								<p>Bug: https://bugs.eclipse.org/bugs/show_bug.cgi?id=123456 <br>
								Signed-off-by: John Doe &lt;johndoe@gmail&gt;</p>
						
							</li>
						</ul>
						
						<p>With the message done, click commit.</p>
						
						<p>Example for CommitTwo:</p>
						
						<ul>
							<li>
								<p>[123456] Change the initial value of temp variable</p>

								<p>The initial value of the temp variable was changed to 1 instead of zero because of weather conditions</p>

								<p>Bug: https://bugs.eclipse.org/bugs/show_bug.cgi?id=123456 <br>
								Change-Id: If0b359ad15268ed179194cf5ad4fb5b2d09b3290 <br>
								Signed-off-by: John Doe &lt;johndoe@gmail&gt;</p>
						
							</li>
						</ul>
						
						<p>With the message done, click commit.</p>
					</li>
					<li>
						<p>Push the commit</p>
						
						<p>In the History View you can see the new commit you have just added. 
						You can access this view by changing the tab from "Git Staging" to "History".
						So far, the commit is only stored locally, and noone else knows about it. 
						It's time to push it to the repository in Eclipse. 
						Right-click on your last commit &rarr; Push commit.... 
						A dialog opens. 
						With the configurations shown, you are trying to push to the develop branch of the Gerrit called refs/heads/develop. 
						But, according to the Gerrit documentation, you should push to the magic branch named refs/for/[branch]. 
						So, in the dialog, instead of the standard develop branch, change to refs/for/develop (instead of reds/heads/develop). 
						Click next, and you'll be asked to introduce your https Gerrit password generated <a href="#ConfigureGerrit">above</a>. 
						The push confirmation notifies that a new branch is being created. 
						Don't worry about that, and click Finish. 
						Enter the password again, and then the push should succeed. 
						If anything fails, the error appears in the log.</p>
					</li>
				</ol>
			</li>
	
		<h3>Option 2: Git on command line</h3>
		
			<p>Use Git on the command line instead of <a href="#EGit">EGit</a> (this one is for the reckless, the knights of the keyboard and especially those afraid of mice).</p>
		
			<p>The following instructions apply to Debian-based Linux systems such as LinuxMint or Ubuntu. 
			It is assumed that you have already created your Eclipse account and signed the ECA as described <a href="#EclipseAccount">above</a>. 
			Also the same <a href="#FindBug">rules</a> for creating a bug report and working on the FORTE code apply. 
			Of course, you can decide yourself which editor you want to use for coding. 
			There are a lot of possibilities out there: VI, Emacs and many more. 
			For code compilation and linking on a Linux system, the GNU compiler suite usually is the best choice. 
			But the details on that won't be addressed here.</p>
			
			 <ol>
				<li>
					<p>Check and install Git command line tools</p>
					
					<p>If you are unsure whether the Git command line tools are already installed on your Linux box, you can enter the following command on Debian based distributions (e.g., LinuxMint, Ubuntu):</p>
					  <code>johndoe@linuxmint ~/$ dpkg --get-selections | grep git</code>
					  <p>If Git tools are already installed, you should get a reply such as:</p>
					  <code>git&emsp;&emsp;install<br>
						  git-core&emsp;&emsp;install<br>
						  git-gui&emsp;&emsp;install<br>
						  git-man&emsp;&emsp;install<br>
						  git-review&emsp;&emsp;install<br>
						  gitk&emsp;&emsp;install<br>
					  </code>
					  <p>If you don't see the output above, you'll need to install the Git tools with the following command:</p> 
					  <code>johndoe@linuxmint ~/$ sudo apt-get update &amp;&amp; sudo apt-get install git</code>
				</li>
				<li>
					<p>Clone FORTE repository to a directory of your choice</p>
					
					<p>First, create a directory in your own home directory and change to it. In my example, this is &frasl;home&frasl;johndoe&frasl;develop&frasl;repos, but you can also choose another.</p>
					<code>johndoe@linuxmint ~/$ mkdir -p develop/repos<br>
					johndoe@linuxmint ~/$ cd develop/repos
					</code>
					<p>Now it's time to clone the FORTE sources.</p>
					<code>johndoe@linuxmint ~/develop/repos$ git clone https://git.eclipse.org/r/4diac/org.eclipse.4diac.forte<br>
						  Cloning into 'org.eclipse.4diac.forte'...<br>
						  remote: Counting objects: 1, done<br>
						  remote: Finding sources: 100% (1/1)<br>
						  Receiving objects: 100% (2283/2283), 1.27 MiB | 458.00 KiB/s, done.<br>
						  remote: Total 2283 (delta 0), reused 2283 (delta 0)<br>
						  Resolving deltas: 100% (1445/1445), done.<br>
						  Checking connectivity... done.<br>
					</code>
					<p>After cloning, you can have a look at the branches of the repository, but first you'll have to change to the new FORTE source directory created automatically.</p>
					<code>johndoe@linuxmint ~/develop/repos$ cd org.eclipse.4diac.forte<br>
						johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte $ git branch -a<br>
						* master<br>
						remotes/origin/1.8.x<br>
						remotes/origin/HEAD &rarr; origin/master<br>
						remotes/origin/OPC_UA<br>
						remotes/origin/develop<br>
						remotes/origin/master<br>
					</code>
					<p>The &quot;*&quot; indicates the current active branch. Now switch to the &quot;develop&quot; branch, because this is the one, where the commits are supposed to go.</p>
					
					<code>johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte $ git checkout develop<br>
						  Branch develop set up to track remote branch develop from origin.<br>
						  Switched to a new branch 'develop'<br>
					</code>
				</li>
				<li>
					<p>Configure your Git installation to work with Gerrit code review</p>
					<p>You should have already created your Eclipse account and Gerrit login, following the description above. Let's assume that your email account is john.doe@example.com and the login for Gerrit is jdoexy5. We'll set this in the git configuration first.</p>
					<code>johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte $ git config --global user.email "john.doe@example.com"<br>
					  johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte $ git config --global user.name "jdoexy5"
					</code>
					<p>Please note that git config --global settings  are generally stored within a user-specific configuration file. This file is named .gitconfig and is stored in your own home directory and not in the FORTE repository. 
					We'll now create an SSH public key which you need to upload to your Gerrit account later on.</p>
					<code>johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte $ cd ~/.ssh<br>
						johndoe@linuxmint ~/.ssh $ ssh-keygen -t rsa -C "john.doe@example.com"<br>
						Generating public/private rsa key pair.<br>
						Enter file in which to save the key (/home/johndoe/.ssh/id_rsa):<br> 
						Enter passphrase (empty for no passphrase):<br>
						Enter same passphrase again:<br>
						Your identification has been saved in /home/johndoe/.ssh/id_rsa.<br>
						Your public key has been saved in /home/johndoe/.ssh/id_rsa.pub.<br>
						The key fingerprint is:<br>
						4d:c7:4f:8f:71:07:89:cb:c9:dc:e5:ad:54:77:9a:64 john.doe@example.com<br>
					</code>
					<p>You can just accept the default key file location by hitting the return key.
					The Eclipse foundation strongly recommends to use a passphrase for additional security.
					Now copy the newly created public SSH key to your Gerrit account at eclipse.org. 
					Display the contents of the public key file with the following command:</p>
					<code>johndoe@linuxmint ~/.ssh $ cat id_rsa.pub</code>
					<p>Copy everything displayed into your clipboard from the start (including ssh-rsa) to the end (including john.doe@example.com). 
					Now login to your Gerrit account at eclipse.org, click on the small arrow next to your user name displayed in the top-right corner and choose &quot;Settings&quot;. 
					In the menu on the left, choose &quot;SSH Public Keys&quot; and click on &quot;Add key...&quot;. 
					Now paste everything from the clipboard into the text field and click &quot;Add&quot;. 
					Your public key should appear in the list now. 
					We'll check now, whether Gerrit is accepting your key properly. 
					Let's do a small ssh login test.</p>
					<code>johndoe@linuxmint ~/.ssh $ ssh -p 29418 jdoexy5@git.eclipse.org<br>
						The authenticity of host '[git.eclipse.org]:29418 ([198.41.30.196]:29418)' can't be established.<br>
						RSA key fingerprint is 1a:b6:dc:be:0e:1f:ab:01:70:aa:43:82:4d:54:51:37.<br>
						Are you sure you want to continue connecting (yes/no)? yes<br>
						Warning: Permanently added '[git.eclipse.org]:29418,[198.41.30.196]:29418' (RSA) to the list of known hosts.<br>
						<br>
						**** Welcome to Gerrit Code Review ****<br>
						<br>
						Hi John, you have successfully connected over SSH.<br>
						<br>
						Unfortunately, interactive shells are disabled.<br>
						To clone a hosted Git repository, use:<br>
						<br>
						git clone ssh://jdoexy5@git.eclipse.org:29418/REPOSITORY_NAME.git<br>
						<br>
						Connection to git.eclipse.org closed.<br>
					</code>
					<p>You'll have to configure the Gerrit Push URL within your Git configuration. 
					Change to the hidden Git directory within the FORTE repository and edit the file named &quot;config&quot;</p>
					<code>johndoe@linuxmint ~/.ssh $ cd ..<br>
						johndoe@linuxmint ~/ $ cd develop/repos/org.eclipse.4diac.forte/.git<br>
						johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte/.git $ nano config<br> 
					</code>
					<p>The following screenshot indicates the parts you need to add or change. 
					Save and exit afterwards.</p>
					<img src="../../html/development/img/cmdPushUrlConfig.png" alt="Configure Gerrit Push URL"/>
				</li>
				<li>
					<p>Create your own commit message template (optional)</p>
					
					<p>You can create a commit message template file, which will be used everytime you do a new commit. 
					You can add helpful comments, so that you don't forget important contents of the message or even add text, which should be part of every commit message. 
					It's just up to you. 
					Change to your home directory and create a new file called .git_commit_msg_template with your favorite text editor. 
					Here I used nano for convenience.</p>
					<code>johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte/.git $ cd /home/johndoe<br>
						johndoe@linuxmint ~/ $ nano .git_commit_msg_template<br>
					</code>
					<p>The following screenshot shows some example content. 
					See <a href="#CommitChanges">above</a> for more details of the message guide</p>
					<img src="../../html/development/img/cmdCreateCommitMsgTemplate.png" alt="Example of commit message template contents"/>
				</li>
				<li>
					<p>Do your first command line commit</p>
					<p>A new commit should always be in relation to a bug in Bugzilla as already mentioned <a href="#FindBug">above</a>. A bug can also add new functionality to FORTE. 
					A single commit should not contain more than 1000 lines of code (yes, you are right, this was already mentioned above, but you can never emphasize this too often). 
					A good approach to check whether something was changed in your local FORTE sources and needs to be committed is the git status command. 
					You should change to your local FORTE Git repository first.</p>
					<code>johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte $ git status<br>
						On branch develop<br>
						Your branch is up-to-date with 'origin/develop'.<br>
						<br>
						Untracked files:<br>
						(use "git add file..." to include in what will be committed)<br>
						<br>
						src/modules/conmeleon_c1/<br>
						<br>nothing added to commit but untracked files present (use "git add" to track)<br>
					</code>
					<p>In the example above, I only added an empty directory, which is now recognized by Git as untracked. 
					If you want to add some new files, just copy them to your local FORTE repository or edit existing files. 
					Git will recognize the changes and you'll see the files with the &quot;git status&quot; command. 
					To be able to commit anything, the respective files need to be added first. 
					In this way, the files will be moved to the so called staging area. 
					So flex your fingers and add properly.</p>
					<code>johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte $ git add src/modules/conmeleon_c1/util<br>
						johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte $ git status<br>
						On branch develop<br>
						Your branch is up-to-date with 'origin/develop'.<br>
						<br>
						Changes to be committed:<br>
						(use "git reset HEAD file..." to unstage)<br>
						<br>
						new file: src/modules/conmeleon_c1/util/fileres.cpp<br>
						new file: src/modules/conmeleon_c1/util/fileres.h<br>
						new file: src/modules/conmeleon_c1/util/uncopyable.h<br>
						<br>
						Untracked files:<br>
						(use "git add file..." to include in what will be committed)<br>
						<br>
						src/modules/conmeleon_c1/CMakeLists.txt<br>
						src/modules/conmeleon_c1/gpio/<br>
						src/modules/conmeleon_c1/processinterface.cpp<br>
						src/modules/conmeleon_c1/processinterface.h<br>
						src/modules/conmeleon_c1/spi/<br>
					</code>
					<p>Now we do the commit itself. 
					Don't forget the -s option for automatic sign-off which is required by the org.eclipse.4diac.forte project and to follow the <a href="#CommitChanges">message guide</a> if you didn't do it already as a template. 
					After the git commit command the default editor will be opened with your commit message template and you have to enter the message information (Bugzilla ID, what was changed and why and the URL to the bugzilla entry).</p>
					<code>johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte $ git commit -s<br>
						[develop 3a8de79] [495477] Add conmeleon support to forte<br>
						3 files changed, 272 insertions(+)<br>
						create mode 100644 src/modules/conmeleon_c1/util/fileres.cpp<br>
						create mode 100644 src/modules/conmeleon_c1/util/fileres.h<br>
						create mode 100644 src/modules/conmeleon_c1/util/uncopyable.h<br>
					</code>
					<p>So far so good. 
					This was not really a big deal, was it? 
					The next step is pushing to Gerrit code review and then your new code will be scrutinized by the never sleeping eyes of the project code reviewer. </p>
				</li>
				<li>
					<p>Push to Gerrit</p>
					<p>This is not difficult, if you followed the steps above. 
					You are just a single command away from finishing.</p>
					<code>johndoe@linuxmint ~/develop/repos/org.eclipse.4diac.forte $ git push origin HEAD:refs/for/develop<br>
						Password for 'https://jdoexy5@git.eclipse.org':<br> 
						Counting objects: 38, done.<br>
						Delta compression using up to 2 threads.<br>
						Compressing objects: 100% (8/8), done.<br>
						Writing objects: 100% (9/9), 3.84 KiB | 0 bytes/s, done.<br>
						Total 9 (delta 3), reused 0 (delta 0)<br>
						remote: Resolving deltas: 100% (3/3)<br>
						remote: Processing changes: new: 1, refs: 1, done<br> 
						remote: ----------<br>
						remote: Reviewing commit: 3a8de79f<br>
						remote: Authored by: jdoexy5 (john.doe@example.com)<br>
						remote: <br>
						remote: The author is not a committer on the project.<br>
						remote: The author has a current Contributor License Agreement (CLA) on file.<br>
						remote: The author has "signed-off" on the contribution.<br>
						remote: <br>
						remote: This commit passes Eclipse validation.<br>
						remote: <br>
						remote: New Changes:<br>
						remote: https://git.eclipse.org/r/74832 [495477] Add conmeleon support to forte<br>
						remote: <br>
						To https://jdoexy5@git.eclipse.org/r/4diac/org.eclipse.4diac.forte<br>
						* [new branch] HEAD &rarr; refs/for/develop<br>
					</code>
					<p>You did it, good job! 
					Now it's the reviewer's turn and you'll see his or her comments in the Gerrit code review webpage.</p>
				</li>
			</ol>
		</li>
	
	<h2>Things to keep in mind for contributions:</h2>
	
		<ul>
			<li>
				<p>When creating new files for the project, add the copyright terms at the beginning. Following the year of modification, add the name. Additionally, add your name below "Contributors", together with a short description of your contribution. 
				Example code:<br>
				<code> Copyright (c) 20.. Name<br>
				<br>
				 This program and the accompanying materials are made available under the<br>
				 terms of the Eclipse Public License 2.0 which is available at<br>
				 http://www.eclipse.org/legal/epl-2.0.<br>
				 <br>
				 SPDX-License-Identifier: EPL-2.0<br>
				<br>
				Contributors:<br>
			     - Name: Short description of the contribution</code></p>
			</li>
			<li>
				<p>Always contribute to a bug.</p>
			</li>
			<li>
				<p>Put the bug number between brackets in the subject of the commit message, and the link to the bug in the footer.</p>
			</li>
			<li>
				<p>Don't forget to sign the commit.</p>
			</li>
			<li>
				<p>Use the Gerrit <a target="_blank" href="https://git.eclipse.org/r"> website </a> to see the commits you pushed and their status.</p>
			</li>
			<li>
				<p>Don't be afraid of contributing code.</p>
			</li>
			<li>
				<p>Use the forums in case of doubt.</p>
			</li>
			<li>
				<p>Find more info <a target="_blank" href="https://wiki.eclipse.org/Development_Resources/Contributing_via_Git"> here</a>.</p>
			</li>
			
		</ul>

<h1>Where to go from here?</h1>

<p>Back to Development index:</p>

<p><a href="../../html/development/developmentIndex.html">Development Index</a></p>

<p>If you want to go back to the Start Here page, we leave you here a fast access:</p>

<p><a href="../../html/startHere/startHere.html">Start Here page</a></p>

<p class="goToTop">Or <a href="#topOfPage">Go to top</a></p>

</body>
</html>
